/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements.  See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License.  You may obtain a copy of the License at
*
*     http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package jakarta.servlet;

/**
 * Enumeration of dispatcher types. Used both to define filter mappings and by
 * Servlets to determine why they were called.
 * 这些调度类型对应于不同的Servlet生命周期调度，使开发人员能够根据需要执行相应的操作。例如，可以根据调度类型来区分请求的来源、处理转发或包含请求、处理错误请求、或异步处理请求。
 * 需要注意的是，这些调度类型并不是互斥的，一个Servlet可能被多种调度类型调用，具体取决于触发调用的方式和容器的行为。
 * 在实际使用中，可以通过检查当前的DispatcherType来确定Servlet的调度类型，并根据不同的类型执行相应的逻辑和处理。
 * @since Servlet 3.0
 */
public enum DispatcherType {

    /**
     * {@link RequestDispatcher#forward(ServletRequest, ServletResponse)}
     * 表示当前Servlet是通过转发调度（例如 RequestDispatcher.forward()）进行调用的。转发调度是由Servlet容器内部发起，在同一个请求中被调用的Servlet。
     */
    FORWARD,

    /**
     * {@link RequestDispatcher#include(ServletRequest, ServletResponse)}
     * 表示当前Servlet是通过包含调度（例如 RequestDispatcher.include()）进行调用的。包含调度是通过一个请求将多个Servlet链接在一起，共同处理请求的。
     */
    INCLUDE,

    /**
     * Normal (non-dispatched) requests.
     * 表示当前Servlet是通过请求调度（例如 RequestDispatcher.forward() 或 HttpServletResponse.sendRedirect()）进行调用的。
     * 该调度类型是在客户端（浏览器）发起的请求中直接调用 Servlet
     */
    REQUEST,

    /**
     * {@link AsyncContext#dispatch()}, {@link AsyncContext#dispatch(String)}
     * and
     * {@link AsyncContext#addListener(AsyncListener, ServletRequest, ServletResponse)}
     * 表示当前Servlet是通过异步调度（例如 AsyncContext.dispatch()）进行调用的。异步调度是在Servlet容器中启动的异步请求处理中使用的。
     */
    ASYNC,

    /**
     * When the container has passed processing to the error handler mechanism
     * such as a defined error page.
     * 表示当前Servlet是通过错误调度（例如 RequestDispatcher.error()）进行调用的。错误调度是在出现错误/异常时由容器发起的，用于处理错误请求的Servlet。
     */
    ERROR
}
